Script/Plugin Development Notes
 
If you have any questions or problems developing scripts or plugins for Samurize, be sure to stop by the samurize.com forums for help from other community members and the development team.
 
Scripts
 
Writing scripts to work in Samurize is very simple if you are fluent in any scripting language. Samurize currently supports VBscript, Javascript, PerlScript and Python. If you do not know any of these languages but have a background in any programming languages, picking either of these up is quite simple as there a lot of tutorials available on the net. You can also look at exiting scripts that have been written for Samurize to see how they work.

All you have to do to create a script in Samurize is declare a function and set the function's return value to the data you want to display. Here is a simple script (VBscript and Javascript versions) that outputs a well-known phrase:
    ' VBscript hello world script
    Function Hello()
	Hello = "Hello World!"
    End Function
    
    // Javascript hello world script
    function Hello() {
	return "Hello World!"   
    }
    
That's all there is to it. Just fill in the function body with your own code, rename the function (or create more as need be) and add function parameters if desired. Save the script to your Samurize/scripts directory as a .vbs (VBscript)/.js (Javascript)/.pls (PerlScript*)/.py (Python*)/.rb (RubyScript**)/.php (PHPScript***) file and you're set.

The only limitation to using scripts in Samurize is that you can't use any message box popups or Sleep commands because they interfere with Samurize's execution.

* You must have ActivePerl/ActivePython installed and registered with the Windows Scripting Host to use these kinds of scripts in Samurize. You can get them from www.activestate.com.
** You must have RubyScript installed and registered with the Windows Scripting Host. You can get it from http://arton.hp.infoseek.co.jp/index.html.
*** You must have PHPScript installed and registered with the Windows Scripting Host. Download the php5activescript.dll from here and make sure you have at least PHP 5.0 installed.
 
Plugins
 
Writing plugins for Samurize is a little trickier than writing scripts because you need some knowledge of C, C++, Delphi or some other compiled language that is capable of creating Dynamic Linked Libraries (DLLs).

Plugins have been successfully developed in C++, Delphi and Powerbasic (a variation of Visual Basic) that work with Samurize, although it may be possible to create plugins in other compiled languages.

The source code for a number of sample plugins is provided in your Samurize/plugins directory:
  • hello_word.dpr (written in Delphi 7) and Helloworld_C++.zip (written in C++) are both source plugins written under the v1.0 SDK.

  • sdksample.dpr (written in Delphi 7) and TestVis.zip (written in C++) are source and/or visual plugins written under the v2.0 SDK.
    Both of these plugins use graphics libraries (Graphics32 for sdksample.dpr, GDI+ for TestVis.zip) to render graphics - you will need to download these in order to compile these to plugins.
Read the comments in the source code of these plugins to understand how they work and to help you design your own plugins.

For a full list of the functions the SDK provides (and comments about each function), check the sdksample.dpr code.

Samurize plugins need to be placed in your Samurize/plugins folder.
 
Samurize API
 
Plugins (and in most cases, other applications) are also capable of communicating with Samurize via the Samurize API. The API is very similar to the Winamp API in that communation is done by sending messages to the Samurize windows.

// Messages
// note that some messages do not apply to all clients (eg. the taskbar client has no tray icon)

// Actions
const int WM_SAM_RELOAD_CONFIG            = 40000; // tells Samurize to reload
const int WM_SAM_PAUSE                    = 40001; // sets pause (use wparam=0 for unpause, 1 for pause)
const int WM_SAM_SHOW                     = 40002; // sets Samurize visible (use wparam=0 for hide, 1 for show)
const int WM_SAM_SHOWTRAYICON             = 40003; // set tray icon visibility (use wparam=0 for hide, 1 for show)
const int WM_SAM_EXIT                     = 40004; // exits Samurize
const int WM_SAM_SET_CLIENTSETTING        = 40005; // sets client settings according to wparam (see below), 0=false, 1=true
const int WM_SAM_SET_CLIENTPOSITION       = 40006; // sets client behaviour (use wparam, 0=on top, 1=pinned, 2=normal, 3=abs. on top)
const int WM_SAM_SET_TASKBARPOSITION      = 40061; // sets taskbar client position
							// use wparam=0 for horizontal position (lparam: 0=left, 1=center, 2=right)
							// use wparam=1 for vertical position (lparam: 0=top, 1=middle, 2=bottom)
const int WM_SAM_LOAD_CONFIGFILE          = 40007; // pass a pointer to a string as lparam - tells Samurize to load that config file.
                                         // (eg. "myconfig.ini")
const int WM_SAM_SET_REFRESHINTERVAL      = 40008; // set the client refresh rate using wparam
const int WM_SAM_EDITCONFIGFILE           = 40009; // opens the config editor with the currently loaded config
const int WM_SAM_TOGGLE_PAUSE             = 40010; // toggles Samurize's pause status, returns the new status (1=paused, 0=unpaused)
const int WM_SAM_TOGGLE_SHOW              = 40011; // toggles Samurize's visible status, returns the new status (1=visible, 0=hidden)
const int WM_SAM_TOGGLE_SHOWTRAYICON      = 40012; // toggles Samurize's tray icon visible status, returns the new status
                                         // (1=visible, 0=hidden)
const int WM_SAM_TOGGLE_CLIENTSETTING     = 40013; // toggles Samurize's client settings according to wparam (see below),
                                         // returns the new status (1=true, 0=false)

const int WM_SAM_SERVER_XML_OUTPUT        = 40017; // sets Samurize XML output (use wparam=0 for disable, 1 for enable)
const int WM_SAM_SERVER_PNG_OUTPUT        = 40018; // sets Samurize PNG output (use wparam=0 for disable, 1 for enable)

// Information

// strings
const int WM_SAM_GET_INSTANCENAME         = 40020; // returns pointer to string containing instance name
const int WM_SAM_GET_CONFIGNAME           = 40021; // returns pointer to string containing config file name
const int WM_SAM_GET_CONFIGPATH           = 40022; // returns pointer to string containing full path to config file
const int WM_SAM_GET_LANGUAGEFILE         = 40023; // returns pointer to name of language file

// integers
const int WM_SAM_GET_CLIENTPOSITION       = 40050; // gets client behaviour (use wparam, 0=on top, 1=pinned, 2=normal, 3=abs. on top)
const int WM_SAM_GET_CLIENTSETTING        = 40051; // gets client settings according to wparam (see below), 0=false, 1=true
const int WM_SAM_GET_REFRESHINTERVAL      = 40052; // returns client refresh rate
const int WM_SAM_GET_TASKBARPOSITION      = 40060; // returns taskbar client position
							// use wparam=0 for horizontal position (0=left, 1=center, 2=right)
							// use wparam=1 for vertical position (0=top, 1=middle, 2=bottom)

// booleans, returns 0 for false, 1 for true
const int WM_SAM_IS_PAUSED                = 40080;
const int WM_SAM_IS_VISIBLE               = 40081;
const int WM_SAM_IS_TRAYICONVISIBLE       = 40082;


// config editor messages
const int WM_SAM_CONFIGEDITOR_SETDEFAULTS         = 40100; // sets defaults for the selected visual plugin meter
const int WM_SAM_CONFIGEDITOR_REFRESHMETER        = 40101; // refreshes the selected meter


// all samurize clients & config editor
const int WM_SAM_ENVIRONMENT                      = 39999; // returns the environment of the plugin
const int SAM_DESKTOPCLIENT                       = 1; // desktop client (client.exe)
const int SAM_TASKBARCLIENT                       = 2; // taskbar client (taskbar.dll)
const int SAM_SERVER                              = 3; // server (samurizeserver.exe)
const int SAM_CONFIGEDITOR                        = 0; // config editor (config.exe)

// sending data(external apps) using WM_COPYDATA
const int SAM_LOAD_CONFIG             = 1000; // tells Samurize to load a config

// wparams for use with WM_SAM_GET_CLIENTSETTING & WM_SAM_SET_CLIENTSETTING
const int SAM_CLIENT_LOCKED           = 2000;
const int SAM_CLIENT_CLICKTHRU        = 2001;
const int SAM_CLIENT_USEDESIGNPOS     = 2002;
const int SAM_CLIENT_SNAP             = 2003;
const int SAM_CLIENT_SNAPTOCLIENTS    = 2004;
    
If you installed Samurize with the Plugin Example option enabled, you can also see the entire list of supported messages in samurize.h inside TestVis.zip located in your Samurize/plugins directory.
 
Proxy Settings
 
Samurize users can set their proxy settings in the Preferences window in the Config Editor. If you want to provide proxy support in your script or plugin, the proxy settings are saved in the registry under the path HKEY_CURRENT_USER\Software\Serious Samurize\General in the following keys:

UseProxy - indicates whether a proxy should be used or not (0=no, 1=yes)
ProxyServer - proxy server (IP address or name)
ProxyPort - proxy port
ProxyUsername - proxy username
ProxyPassword - proxy password

It is the script/plugin author's responsibility to add proxy support to their code where necessary, otherwise these settings will have no effect.